/*
 * Copyright (c) 2008, Solido Systems
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * Redistributions of source code must retain the above copyright notice, this
 * list of conditions and the following disclaimer.
 *
 * Redistributions in binary form must reproduce the above copyright notice,
 * this list of conditions and the following disclaimer in the documentation
 * and/or other materials provided with the distribution.
 *
 * Neither the name of Solido Systems nor the names of its contributors may be
 * used to endorse or promote products derived from this software without
 * specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */

// ticket 533669

package com.solidosystems.objectkitchen.storage;

import java.util.*;
import java.io.*;
import com.solidosystems.objectkitchen.data.*;

public interface Storage{
	/**
	 * Get a document based on it's unique id.
	 * If the document doesn't exist or has been deleted null will be returned.
	 *
	 * @param id the full id of the document
	 * @return The document, if it exists, null otherwise
	 */
	public Document getDocument(String id) throws IOException;
	
	/**
	 * Gets a specific version of a document based on it's unique id and a version number.
	 * If the document or the specified version doesn't exist, null will be returned.
	 *
	 * @param id the full id of the document
	 * @param version the version of the document
	 * @return The document, if it exists, null otherwise
	 */
	public Document getDocument(String id, int version) throws IOException;
	
	/**
	 * Get a document based on it's unique id.
	 * If the document doesn't exist it will be created.
	 *
	 * @param id the full id of the document
	 * @return The requested document
	 */
	public Document getOrCreateDocument(String id) throws IOException;
	
	/**
	 * Stores a document.
	 *
	 * @param doc the document to store.
	 */
	public void putDocument(Document doc) throws IOException;

	/**
 	 * Deletes a document.
 	 *
 	 * @param id the id of the document to delete.
 	 */
	public void deleteDocument(String id) throws IOException;

	/**
 	 * Determines wether or not a document exists.
 	 *
 	 * @param id the id of the document to look for.
	 * @return true if the document exists, false otherwise.
 	 */
	public boolean hasDocument(String id) throws IOException;

	/**
	 * Stores an attachment for a document.
	 *
	 * @param id the id of the document
	 * @param title the title of the attachment
	 * @param data the raw data to store.
	 */
	public void putAttachment(String id,String title,byte[] data) throws IOException;
	
	/**
	 * Fetches an attachment from a document.
	 *
	 * @param id the id of the document
	 * @param title the title of the attachment
	 * @return the raw data stored in the attachment, or null if the attachment did not exist
	 */
	public byte[] getAttachment(String id,String title) throws IOException;
	
	/**
	 * Deletes an attachment from a document.
	 *
	 * @param id the id of the document
	 * @param title the title of the attachment to delete
	 */
	public void deleteAttachment(String id,String title) throws IOException;
}